home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 25 / Cream of the Crop 25.iso / os2 / faxd_07.zip / READ.ME < prev    next >
Text File  |  1997-03-19  |  11KB  |  272 lines

  1. Version 03 19 March 97
  2.  
  3. DISCLAIMER
  4.  
  5. I am not a programmer and make no representations or warranties about these
  6. programs. I wrote them for myself and use them myself without problems. You
  7. may use them entirely at your own risk. I have used the names of various
  8. commercial products in this read.me file. They are trademarks of the firms
  9. that release them. 
  10.  
  11. LIMITATIONS
  12.  
  13. These are my first VXREXX applications. They are primitive and crude. There
  14. are many improvements to be made -- over time. Right now, this project
  15. stretched the limits of my abilities and the result gets the job done. Some
  16. day I will build a phonebook thread to keep the phonebook sorted and up to
  17. date. And some other features.
  18.  
  19. DESCRIPTION
  20.  
  21. I have a two line BrookTrout board and two line FaxWorks installation in my
  22. office. I have been frustrated when on the road -- which is often -- with
  23. the cost of sending faxes from hotels, especially overseas. Fax modems are
  24. also not as reliable. So I wrote this package. It takes incoming files,
  25. sends them as faxes and notifies me of their status. There are two parts at
  26. the moment: FaxD.exe and FxFTP. 
  27.  
  28. FAXD
  29.  
  30. The fax server can be any computer running Faxworks. You will probably
  31. require a full time internet connection to make this work the way it is
  32. intended.
  33.  
  34. The fax server runs FAXD.EXE from a directory, which is the Working
  35. Directory. It searches that directory at intervals for any file of the
  36. pattern *.env. If it finds one, it parses the information in that file and
  37. posts the TIF or FAX file to FaxWorks. It then tries to detect the status
  38. of that transaction and emails you of the result.
  39.  
  40. The FAXD.CFG file has to exist in the working directory for this program to
  41. work. You can edit it using the System Editor.
  42.  
  43. There are four threads: 
  44.  
  45. The main thread launches the other three and sends periodic instructions to
  46. the two working threads to do their business. It also displays current
  47. activities on the little program window.
  48.  
  49. The timer thread sends "ticks" to the main thread every ten seconds.
  50.  
  51. The Fax Redirection thread searches for *.env files when told to by the
  52. parent thread. If it finds one, it parses it, deletes it and replaces it
  53. with a file with the same name and the extension: .sts. It then adds the
  54. file to the FaxWorks queue. If it is a TIF file, it adds it as an edited
  55. file and then sends it. If the file is not in the working directory, the
  56. complete path must be included. During this time it posts the file name it
  57. is working on and the index number assigned by FaxWorks to the parent
  58. thread for display. These are transient displays and are just for casual
  59. monitoring and debugging.
  60.  
  61. The status thread is totally decoupled from the Redirection thread. It is
  62. launched by the parent thread. It searches for any *.sts files in the
  63. working directory. It then reads the file and looks at FaxWorks for the
  64. job's status. FaxWorks REXX does not work entirely as documented under all
  65. circumstances, so this part is still rough. If the status is "SENT" then it
  66. goes into its notification phase. Otherwise, it tries to determine if the
  67. status is a final one (no remaining resends) and sends out email
  68. notification if it is. It also posts the job status and retry count to the
  69. main thread for display. The status display items (bottom) and the two
  70. redirection activity display items (top) are not directly related. The top
  71. shows the CURRENT activity (with a one cycle persistence) of the
  72. redirection thread, while the bottom does the same for the status thread.
  73. They might be working on different jobs at any time.
  74.  
  75. FXFTP 
  76.  
  77. FxFTP.EXE runs on the client (my notebook). It automatically creates the
  78. envelope file and uploads it and the fax or tiff file that will be sent to
  79. the target directory on the server. It uses the EWS package: TCPIP REXX FTP
  80. API. YOU WILL NEED THAT TO RUN THIS PROGRAM. The file "RXFTP.DLL" ought to
  81. be in your OS2/DLL subdirectory.
  82.  
  83. FxFTP is bi-threaded. The FTP process is a separate thread that
  84. communicates to the main thread via REXX queues. If the FTP thread is busy
  85. when a job is sent to it, the job remains in the queue until it is free.
  86. You can continue using the main thread to create envelopes while the FTP
  87. thread is sending. The FTP thread disables the QUIT button to prevent
  88. interruptions. It also keeps the main thread informed about the file name
  89. it is working on and how many jobs it has processed since it was launched.
  90.  
  91. FxFTP does nothing at all to change or move the fax or tiff file. It merely
  92. creates a file with a random name and an "env." extension and puts it in
  93. the dedicated directory on the client system. It then uploads via ftp that
  94. file and the file it references. As it works now, it deletes the envelope
  95. file on the client but leaves a copy of the file to send on the server. (A
  96. future version will allow re-sending without re-uploading.) The server
  97. script deletes the envelope file and replaces it with a status file -- or
  98. else it would send it out forever.
  99.  
  100. The phonebook is a simple ASCII file. The name, company and faxphone must
  101. be in that order and comma separated. If you leave out an item, put in the
  102. comma! Do not use commas within a name, company name or phone number. After
  103. writing in an entry, pushing the proper button adds it to the phonebook.
  104.  
  105. The SEND button does not work unless a file and recipient have been
  106. selected. Selecting the "Cover Sheet?" Button adds a default cover sheet,
  107. based on the server's setup. (A future version will allow customization.)
  108. You can type up to 250 characters in the comment window. Do not use commas
  109. or CRLF's as these may cause problems with Faxworks. (I am working on this
  110. aspect.) 
  111.  
  112. The FxFTP.CFG file has to exist in the working directory for this program
  113. to work. You can edit it using the System Editor.
  114.  
  115. NOTIFICATION
  116.  
  117. Notifications are send via email with the subject: "FxReDirect Status". I
  118. use a REXX script for PMMail on the client that detects these status
  119. reports and, upon successful sending of the fax uses FTP REXX to delete the
  120. fax or tiff file on the server updates a FxFTP log.
  121.  
  122. INSTALLATION
  123.  
  124. This package requires both RxFTP.DLL and the runtime VXREXX DLL to operate.
  125. It also requires the RexxUtil functions.
  126.  
  127. Just create a directory like EFax or FXFTPfor the client software and FAXD
  128. or FxReDirect for the server software. Put all the appropriate files in it.
  129. Edit the config files. Good luck.
  130.  
  131. FAXD.CFG
  132.  
  133. To: xxx@yyy.zzz
  134. From: aaa@bbb.ccc
  135. d:\FaxWorks_directory
  136. FaxWorks_Activity_Report
  137. n
  138. n
  139. n
  140. -a[f]
  141.  
  142. Lines one and two are the TO and FROM lines for email notification. 
  143.  
  144. Line three is the complete path of the Faxworks installation on the sever.
  145.  
  146. Line four is the filename of the activity report in the FaxWorks directory.
  147. I use activity.rpt. You set this up from Faxworks settings.
  148.  
  149. Line five is the number of total tries (retries plus 1) set in FaxWorks.
  150.  
  151. Line Six is for setting the interval for redirecting faxes. The number is
  152. the number of ten second intervals the system waits to trigger the redirect
  153. thread. So, a "6" means one minute. (I use a 3)
  154.  
  155. Line seven is the same for the notify thread. I use a longer period. (I use
  156. a 7).
  157.  
  158. The last line allows you to configure the sendmail command for the version on
  159. your system. My Warp 4 machines want '-a', my Warp 3 machine needs '-af'.
  160.  
  161. FXFTP.CFG
  162.  
  163. phonebook_name
  164. d:\FxReDirect_on_server
  165. d:\FaxWorks_directory
  166. xxx.yyy.zzz
  167. ftp_username
  168. ftp_password
  169.  
  170. Line one is the name of the phonebook file in the working directory.
  171.  
  172. Line two is the complete path to the directory on the target server in
  173. which envelope and fax files are to be sent via ftp. 
  174.  
  175. Line three is the local FaxWorks Directory -- or any directory that you
  176. want to be searched by default for files to send. (The program looks for
  177. *.TIF and *.FAX files by default.)
  178.  
  179. Line four is the address (name or dotted IP address) of the server.
  180.  
  181. Lines five and six are your user name and password, respectively, on the
  182. server for ftp.
  183.  
  184. ENVELOPE FILES
  185.  
  186. TO: SendToData
  187. FROM: *,*,*,*
  188. FILE:RemotePath\RemoteFile
  189. INFO: Comment,*,FxReDirect,*,n 
  190. AT: 
  191. LOCALNAME: File2Fax
  192.  
  193. This is the exact format. Capitals ought to be used for the Tags, as in the
  194. example. 
  195.  
  196. SendtoData is in the expected Faxworks format: name,company,fax_number.
  197. From is in the expected Faxworks format: yourname, yourcompany, yourphone,
  198. yourfax. An "*" indicates that the server default is used. (FxFTP uses
  199. these by default.)
  200.  
  201. The FILE: line tells the server where it is to find the FAX or TIF file to
  202. send. If you upload the file to the same directory as the envelope file,
  203. you still have to put the complete path in. Or, if the file already exists
  204. on the server, you have to specify the path and file name.
  205.  
  206. INFO line is more Faxworks standard stuff. Comment is your comment. If it
  207. is blank, keep the comma. n is a 0, 1 or 2. 2 means no cover sheet. 1 means
  208. a full page cover sheet. 0 means a short cover sheet. The other two are to
  209. set the BMP or CVR file for the cover sheet and to enable or disable the
  210. fax header at the top of pages. The page header is in position two and the
  211. cover sheet file designator is in position four.
  212.  
  213. AT line is the time and date to send. I usually leave it blank.
  214.  
  215. The last line is ignored by the server. It is merely to tell FxFTP what
  216. file to upload to the server. It is added automatically by FxFTP but is not
  217. required at the receiving end.
  218.   
  219. FTP INFO
  220.  
  221. As I said, I use the REXX FTP API in FxFTP. You could also use any FTP
  222. client to transfer the file or files. The envelope should always go last --
  223. for obvious reasons.
  224.  
  225. I use the Hethmon FTPD on the server. Any one should work. Your username
  226. and password combination should give you put, get and delete access to the
  227. target directory on the server.  
  228.  
  229. The FAXD program does not care how files get into the directory. You could,
  230. for example, email them to your server and have a REXX Exit move the FAX or
  231. TIF file to the target directory and create an envelope file there. You
  232. could then have your server log onto the Internet at Intervals and retrieve
  233. mail.
  234.  
  235. COST
  236.  
  237. I feel guilty asking for money for something this crude. But, why should
  238. you benefit from my hours of agony trying to figure out why my password
  239. showed up as a directory name? Or why leaving the file name blank caused
  240. another file to be sent? So this is charity honorware.
  241.  
  242. If you like it and intend to use it, send me money. Put a $20 bill (or a
  243. $10 bill if you cannot afford that) or equivalent in an envelope and send
  244. it to:
  245.  
  246. Chris Barr
  247. PO Box 1661
  248. Center Harbor, NH 03226
  249.  
  250. Indicate whether you want the money used towards:
  251.  
  252. A scholarship or
  253.  
  254. A political contribution.
  255.  
  256. If the former, it will go to pay for private schooling for a little boy in
  257. the Caribbean. (Full disclosure: His parents, local island people, are
  258. friends of mine. My wife and I are the boy's Godparents. He is extremely
  259. bright and we want to help pay for his schooling at the "English School," a
  260. very expensive school mostly attended by the children of American and
  261. English expats.) 
  262.  
  263. If the latter, it will go to the RNC. (I am a Republican.)
  264.  
  265. If you prefer not to pay, please do not use it for any commercial purpose
  266. or for any purpose after 30 days.
  267.  
  268. EMAIL
  269.  
  270. I am cbarr@ibm.net. I cannot guarantee to answer.
  271.  
  272.